Inside Macintosh: QuickTime Components
While the base media handler isolates your component from the details of media data access, your derived media handler still needs to keep track of certain information in order to support movie playback and creation. This section discusses functions that help your media handler manage its information.
Your media handler may store proprietary information in its media. The Movie Toolbox calls two media handler functions in order to give you an opportunity to retrieve or store this information. The MediaPutMediaInfo function allows you to store your special information in your media. The MediaGetMediaInfo function delivers that data to your media handler.
The Movie Toolbox tells your media handler when its track has been enabled or disabled by calling your MediaSetActive function. The Movie Toolbox prepares your handler for playback by calling your MediaPreroll function. Whenever your media's playback rate changes, the Movie Toolbox calls your MediaSetRate function. Whenever the track that uses your media is edited, the Movie Toolbox calls your MediaTrackEdited function.
If the Movie Toolbox has called its SetMediaSampleDescription function on a sample description, it uses the MediaSampleDescriptionChanged function to notify your media handler of the change.
The Movie Toolbox allows tracks to be identified by various characteristics. For instance, it is possible to request that all tracks containing audio information be searched. To determine whether a track has a given characteristic, the Movie Toolbox queries the media handler for each track. The Movie Toolbox calls the MediaHasCharacteristic function with the specified characteristic.
The Movie Toolbox uses two functions to inform you about changes to your media's time environment. The MediaSetMediaTimeScale function allows the Movie Toolbox to change your media's time scale. The MediaSetMovieTimeScale function allows the Movie Toolbox to tell you when the movie's time scale has changed.
The MediaPutMediaInfo function allows your derived media handler to store proprietary information in its media.
pascal ComponentResult MediaPutMediaInfo (MediaHandler mh,
Handle h);
The Movie Toolbox uses the MediaPutMediaInfo function to provide you an opportunity to store private data in your media. You determine the format and content of this data. The base media handler stores some information for you, including the media's transfer mode, opcolor, and sound balance. However, you may need to store additional information. For example, you may want to place a version number in each media you create.
Whenever the Movie Toolbox opens your media, it provides this private data to your media handler by calling your MediaGetMediaInfo function, which is described next.
Note that the Movie Toolbox may call this function before it calls your MediaInitialize function.
Your derived media handler should support this function if you need to store private data in your media.
The MediaGetMediaInfo function allows your derived media handler to obtain the private data you have stored in your media.
pascal ComponentResult MediaGetMediaInfo (MediaHandler mh,
Handle h);
If you placed private data into your media, the Movie Toolbox calls your media handler's MediaPutMediaInfo function whenever it opens your media. Your media handler determines the format and content of this private data. Note that the Movie Toolbox may call this function before it calls your MediaInitialize function.
Your derived media handler should support this function if you store private data in your media.
The MediaSetActive function allows the Movie Toolbox to enable and disable your media.
pascal ComponentResult MediaSetActive (MediaHandler mh,
Boolean enableMedia);
The Movie Toolbox calls your derived media handler's MediaSetActive function whenever your media is either enabled or disabled. Initially, your media is disabled. Subsequently, the enabled state of your media is controlled by the state of the track that is using your media. When that track is enabled, your media is enabled; when that track is disabled, your media is disabled. Applications can control the enabled state of a track by using the Movie Toolbox's SetTrackEnabled function.
Your derived media handler should support this function if you perform your own scheduling or if your media handler uses significant amounts of temporary storage. If you are doing your own scheduling (that is, you have set the handlerNoScheduler flag to 1 in the flags parameter of the MediaSetHandlerCapabilities function--see MediaSetHandlerCapabilities for more information about this function), your media handler needs to keep account of the media's active state so that you can properly respond to Movie Toolbox requests. When your media is disabled, you may choose to dispose of temporary storage you have allocated, so that the storage is available to other programs.
The MediaPreroll function allows the Movie Toolbox to prepare your media handler for playback.
pascal ComponentResult MediaPreroll (MediaHandler mh,
TimeValue time, Fixed rate);
The MediaSetRate function allows the Movie Toolbox to set your media's playback rate.
pascal ComponentResult MediaSetRate (MediaHandler mh,
Fixed rate);
The Movie Toolbox calls your derived media handler's MediaSetRate function whenever the movie's playback rate changes. The Movie Toolbox provides you with a new effective rate for your media. This effective rate accounts for any master time bases that may be in use with the current movie. Consequently, you may use this rate without having to further transform it.
You obtain the initial rate information from the effectiveRate field of the movie parameter structure that the Movie Toolbox provides to your MediaInitialize function.
Your derived media handler should support this function if you perform your own scheduling. If you are doing your own scheduling (that is, you have set the handlerNoScheduler flag to 1 in the flags parameter of the MediaSetHandlerCapabilities function--see MediaSetHandlerCapabilities for more information about this function), your media handler can use this function to determine when your media is playing, and the direction and rate of playback. This information can help you prepare for playback more efficiently.
The MediaTrackEdited function allows the Movie Toolbox to inform your derived media handler about edits to its track.
pascal ComponentResult MediaTrackEdited (MediaHandler mh);
The Movie Toolbox calls your derived media handler's MediaTrackEdited function whenever the track that is using your media is edited. While these edits do not directly affect the data in your media, they can change the way in which the movie uses your media's data.
Your derived media handler should support this function if you are caching location information about track edits, or if you are using any time values in the movie's time base. Whenever the Movie Toolbox calls this function, your media handler should recalculate this type of information.
The MediaSampleDescriptionChanged function allows the Movie Toolbox to inform your media handler that its SetMediaSampleDescription function has been called for a specified sample description.
pascal ComponentResult MediaSampleDescriptionChanged
(MediaHandler mh,
long index);
The Movie Toolbox calls the MediaHasCharacteristic function with a specified characteristic to allow tracks to be identified by various attributes.
pascal ComponentResult MediaHasCharacteristic
(MediaHandler mh,
OSType characteristic,
Boolean *hasIt);
The Movie Toolbox might request the search of all tracks with audio data. For example, to find out if a track has a given attribute, the Movie Toolbox queries the media handler for each track by calling MediaHasCharacteristic with a particular constant specified in the characteristic parameter. If your media handler does not recognize a characteristic, return a value of false .
You should implement this function for any media handler that has characteristics in addition to spatial ones. If you have set the handlerHasSpatial capabilities flag, the base media handler automatically handles the VisualMediaCharacteristic constant for you.
The MediaSetMediaTimeScale function allows the Movie Toolbox to inform your media handler that your media's time scale has been changed.
pascal ComponentResult MediaSetMediaTimeScale
(MediaHandler mh,
TimeScale newTimeScale);
The Movie Toolbox calls your derived media handler's MediaSetMediaTimeScale function whenever your media's time scale is changed. Applications can change your media's time scale by using the Movie Toolbox's SetMediaTimeScale function. When the Movie Toolbox calls this function, your media handler should recalculate any time values you have stored that are expressed in your media's time coordinate system. Changing your media's time scale may also affect media playback.
You obtain the initial media time scale information from the mediaScale field of the movie parameter structure that the Movie Toolbox provides to your MediaInitialize function.
Your derived media handler should support this function if your media handler stores time information that pertains to its media.
The MediaSetMovieTimeScale function allows the Movie Toolbox to inform your media handler that the movie's time scale has been changed.
pascal ComponentResult MediaSetMovieTimeScale
(MediaHandler mh,
TimeScale newTimeScale);
The Movie Toolbox calls your derived media handler's MediaSetMovieTimeScale function whenever the movie's time scale is changed. Applications can change the movie's time scale by using the Movie Toolbox's SetMovieTimeScale function. When the Movie Toolbox calls this function, your media handler should recalculate any time values you have stored that are expressed in the movie's time coordinate system. Changing the movie's time scale may also affect playback of your media.
You obtain the initial movie time scale information from the movieScale field of the movie parameter structure that the Movie Toolbox provides to your MediaInitialize function.
Your derived media handler should support this function if your media handler stores time information in the movie's time coordinate system.